---
title: Troubleshoot ZITADEL
sidebar_label: Troubleshoot
---

You will find some possible error messages here, what the problem is and what some possible solutions can be.

:::tip Didn't find an answer?  
Join or [Chat](https://zitadel.com/chat) or open a [Discussion](https://github.com/zitadel/zitadel/discussions).
:::

## User agent does not correspond

This error appeared for some users as soon as they were redirected to the login page of ZITADEL.
ZITADEL uses some cookies to identify the browser/user agent of the user, so it is able to store the active user sessions. By blocking the cookies the functions of ZITADEL will be affected.

We only found this issue with iPhone users, and it was dependent on the settings of the device.

Go to the settings of the app Safari and check in the "Experimental WebKit Features" if SameSite strict enforcement (ITP) is disabled
Also check if "block all cookies" is active. If so please disable this setting.

To make sure, that your new settings will trigger, please restart your mobile phone and try it again.

**Settings > Safari > Advanced > Experimental Features > disable: „SameSite strict enforcement (ITP)“**

![Same Site Strict Enforvement](/img/manuals/errors/same-site-strict.png)

**Settings > Safari > disable: "Block All cookies"** 
![Block all cookies](/img/manuals/errors/block-cookies.png)

Do you still face this issue? Please contact us, and we will help you find out what the problem is.

## Invalid audience

`invalid audience (APP-Zxfako)`

This error message refers to the audience claim (`aud`) of your token.
This claim identifies the audience, i.e. the resource server, that this token is intended for.
If a resource server does not identify itself with a value in the "aud" claim when this claim is present, then the must be rejected (see [RFC7519](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3) for more details).

You might encounter this error message from ZITADEL, typically when you authenticated with a client in one project and trying to access an application in another project.
You need add a specific [reserved scope](/docs/apis/openidoauth/scopes#reserved-scopes) to add the projectID to the audience of the access token.

The two scenarios should help you troubleshoot this issue:

### Frontend to Backend

You have one project for your frontend application and one project for your backend application.
End-users authenticate to an application in your frontend project.
The frontend then sends requests to the backend, validates the token with ZITADEL's introspection endpoint, and returns a payload to the frontend.
The backend returns the error `invalid audience (APP-Zxfako)`.

You must add the scope `urn:zitadel:iam:org:project:id:{projectId}:aud` to the auth request that is send from the front end.
Replace `projectId` with the projectId of your backend.

### Accessing ZITADEL's APIs

You have a project for a frontend application.
The application should also access the API of your ZITADEL, for example to pull a list of all users and display them on a user page.
End-users authenticate to the application in the frontend project, but when calling the management API you get the error `invalid audience (APP-Zxfako)`.

You must add the scope `urn:zitadel:iam:org:project:id:zitadel:aud` to the auth request that is send from the front end.

When accessing your ZITADEL instance's APIs they act as a resource server.
You can check the Console or via API and see that when you open your default organization there exists a project "ZITADEL" that contains different applications for each API and the Console.
Like in the scenario above the access token requires to have an `aud` claim that includes the "ZITADEL" project.
Instead of `urn:zitadel:iam:org:project:id:zitadel:aud` you could also use `urn:zitadel:iam:org:project:id:{projectId}:aud`, where  `projectId` is the projectId of the Project "ZITADEL".

## WebFinger requirement for Tailscale

The WebFinger requirement and setup is a step a user has to take outside of their IdP set-up. WebFinger is a protocol which supports the ability for OIDC issuer discovery, and we use it to prove that the user has administrative control over the domain and to retrieve the issuer. This is a requirement we have in place for all users, regardless of their IdP, who use custom OIDC with Tailscale.

On their custom domain, e.g example.com, users need to host a WebFinger endpoint at https://example.com/.well-known/webfinger. When queried, this endpoint returns a JSON response detailing the issuer. Users would need to host the endpoint with the link to the ZITADEL issuer. Tailscale only looks up this endpoint once when a user signs up, and will only look up this endpoint again if the user needs to make a configuration change to their identity provider.

The requirements and a set up guide is detailed in the [Tailscale documentation](https://tailscale.com/kb/1240/sso-custom-oidc/).

## Login not possible. The organization of the user must be granted to the project

![Organization must be granted Error](/img/support/login_not_possible_error.png)

ZITADEL is not only capable of handling authentication but also authorization.
This error message tells you, that a project grant is missing from the owner organization to the organization of the authenticating user.

You do have two organizations, an owner (Organization A) and a customer (Organization B).
The Organization A owns a Project, and has to grant it to Organization B, so users are allowed to authenticate.
The error message is shown to users of Organization B that the permission is required, but the project is not granted to Organization B.
![Project Grant Missing](/img/support/project_grant_missing.png)


You do have two possibilities.
1. Disable the permission check
2. Give the permission to the organization

### Disable the permission check

1. Go to the organization, who owns the project, where the user tries to authenticate.
2. Navigate to the general settings of the needed project
3. Disable "Check for Project on Authentication"

![Project Settings](/img/support/check_for_project_on_authentication.png)


### Give the needed permission to the organization

1. Go to the organization, who owns the project, where the user tries to authenticate.
2. Navigate to the grants page of the needed project
3. Click on the "New" button
4. Search for the organization to which you want to grant the project (e.g Organization B)
5. Select the roles you want to grant
6. Click save

![Project Grant for Organization B](/img/support/project_grant_for_customer_b.png)
